* HOL - calculate holidays and write to agenda file

HOL is a program for Psion 3a that can be configured to calculate many
holidays. The program reads a holiday definition file, calculates dates for 
holidays according to the file, and writes the holidays to an agenda file. 
The user interface allows you to select which configured holidays to 
actually use, which years to calculate for, and preview the calculated 
dates on the screen before writing them to the agenda file.

Holidays can be defined relative to a fixed date (e.g. New Years Day), 
a fixed Hebrew date (e.g. Passover), a fixed Islamic date (e.g. the
Islamic New Year's day), a specific weekday (e.g. Midsommardagen; 1st
Saturday after June 20th), Easter, or selected among several dates
depending on a condition.

Style and year symbol can be specified generally and/or for each holiday. 
The holidays are written to the agenda file as untimed day entries in
the default time slot. Some holidays can be written as repeating
entries.

Holiday definition files for Sweden, USA, Holland, Argentina, Uruguay,
Norway, Finland, Germany and the Church of Ireland are included.
Examples of Hebrew and Islamic holidays are also included.


* How to use the program

1) Install the files:
   - Copy HOL.OPO to \OPO\.
   - Copy *.HOL files to \OPD\.
   - Optionally, copy HOL.RSC to \OPD\. This is the help text for HOL.
   - Optionally, copy HOLEDIT.ALS to \APP\. Install it from the system 
     screen with Psion-I if you want to create or edit *.HOL files easily.

2) Examine the *.HOL files with a text editor to see if one suits you. If
   not, you can modify or create one with guidance from EXAMPLE.HOL and 
   the configuration section below.

3) Start the program and open the *.HOL file. All holidays that are 
   defined in the file will be listed on the screen with the style and
   year-symbol specified in the file. The listing can be scrolled with
   PgUp, PgDn, Home, End and arrow keys.

4) Initially all holidays are selected to be written to the agenda file. 
   This is shown with a '*' on each row. Select or deselect holidays
   with Psion-M, Psion-U, Psion-N, Psion-T or the SPACE-key. 
   
   Psion-N selects all holidays that can't be written to the agenda as
   repeating entries. See "How to use repeating entries" below for a tip
   on how to use this.

5) Optionally, calculate and preview the dates with Psion-P. See below
   for information about the dialog box. The dates will be listed on the
   screen. Press ESC to cancel the listing or any other key to
   temporarily pause the listing.

6) To be safe, backup the agenda file you intend to write holidays to.

7) Calculate and write the dates to an agenda file with Psion-W. Select
   an agenda file to write to. See below for more information about the
   dialog box. The dates will be listed on the screen as they are
   written to the file. Press any key to cancel.

Dates are shown in YYYY-MM-DD format, with numeric month. 


** The "Preview/Write holidays" dialog box

When you preview or write holidays a dialog box be shown where you:

 o Enter a year range to calculate dates for. 
 o Select whether HOL should try to use repeating entries ("If
   possible") or not ("No"). See the next section for information about
   when it is possible to use repeating entries.
 o Select whether the Agenda program should show all occurrences of
   repeating entries or only the next outstanding occurrence. This
   corresponds to the "Show"-line in the "Repeat entry" dialog box in
   the Agenda program. If you selected "No" on the previous line this
   information will be ignored.
 o Select an agenda file (only in the "Write holidays" dialog).


** How to use repeating entries.

One of the many useful features of the Psion Agenda program is the
ability to make an entry repeat at various intervals. An entry can e.g.
be set to repeat on a specific date of the year or on the first, second,
third, fourth or last occurrence of a weekday in a month.

Many holidays or special dates that we want to enter into our agenda
file can in fact be made into repeating entries, e.g. New Years Day and
Mother's Day. HOL can be used to write these repeating entries under
certain conditions.

To be able to write a holiday as a repeating entry, the holiday must be
specified in the holiday file with only one of these directives:

  o FIX(m,d)      - Meaning a fixed day D of month M in a year.
                    E.g. FIX(1,1) is January 1st (New Years Day).
                    
  o FLOAT(m,wd,n) - Meaning the N'th weekday WD of month M, where N is
                    1,2,3,4 or -1. E.g. FLOAT(5,0,2) is the second Sunday of
                    June (Mother's Day).

(See the end of this file for more information about holiday files and
directives.)

When you preview or write holidays you can tell HOL to write repeating
entries "If possible". This means that if a holiday is specified using
FIX or FLOAT as shown above, HOL will write the holiday once and make it
a repeating entry. The holiday will be written for the first year in the
specified year range.

I suggest you do the following when using HOL on an agenda file for the
first time:

1) Mark all holidays with Psion-M

2) In the "Write holidays" dialog box, enter a year range. Accept the
   default to use repeating entries if possible.
   
Holidays will now be written for the specified year range, with some
holidays entered only on the first year in the range as repeating
entries.

The next time you use HOL on the same agenda file (when the first
year range has passed) i suggest you:

1) Mark holidays that can't be made to repeat with Psion-N. (The others
   are already in the agenda file as repeating entries)

2) Specify a new year range in the dialog box. 



* License

This program is free software under the terms of the GNU General Public 
License. See the file COPYING.TXT for details.

HOL.OPL was written by Odd Gripenstam <gripenstamol@decus.se>. 
Calendar and holiday routines are translated from lisp code found in
GNU Emacs.

Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994 Free Software
Foundation, Inc.
Copyright (C) 1996 Odd Gripenstam


* Acknowledgements

The help compiler and the code that accesses the help was written by 
Jezar at Psion. It is available as HELPKIT1.ZIP in the archives. 
Contact me if you can't find it.

I would like to thank Patrick Wildenborg, Horacio Hirsch, Mikael Tham,
Knut Utne Hollund, Erlend Leganger, Jokitulppo Vesa, Holger Pfaff and
Brian Mayne for contributing holiday definitions.


* Feedback

No registration is necessary, but I would appreciate if you send me a
mail or postcard if you use the program.  If you try the program and 
*don't* use it, please send me an e-mail and tell me why.

If you write or modify a holiday file, please send it to me and I will
include it in the distribution so more people can benefit from your
effort.

You can reach me at:

  E-mail:      
                gripenstamol@decus.se
  Snail-mail:  
                Odd Gripenstam
                Skagersvagen 14
                120 38 ARSTA
                SWEDEN


* Files in the distribution

This distribution should contain:

  HOL.OPL               Source code for the application
  HOL.OPO               Translated code
  HOL.TXT               This file
  COPYING.TXT           GNU General Public License
  EXAMPLE.HOL           Example holiday file
  AR.HOL                Argentinian holidays
  COFI.HOL              Church of Ireland holidays
  DE.HOL                German holidays
  FI.HOL                Finnish holidays
  NL.HOL                Dutch holidays
  NO.HOL                Norwegian holidays
  SE.HOL                Swedish holidays
  US.HOL                US holidays
  UY.HOL                Uruguayan holidays
  ARUY.HOL              A mix of South American holidays
  HEBREW.HOL            Hebrew holidays
  ISLAMIC.HOL           Islamic holidays
  HOLEDIT.ALS           Text editor alias for \OPD\*.HOL 
  HOL.HLP               Help text source file
  HOL.RSC               Compiled help text
  HOLCHANG.TXT          A history of changes to the files.


* Translation

The program can be run as an APP if you uncomment the APP/ENDA section
in the beginning of HOL.OPL.

Unfortunately, the source file HOL.OPL is too big to be translated on
the Psion. You can translate the file on a PC with the MS-DOS translator
S3ATRAN, or you can split the file in two parts before copying it to the
Psion. There is a commented LOADM statment in the first procedure that
you can use.


* Other resources

Here are some other resources related to holidays and the Psion agenda.
They are all available on the net. You can mail me if you have trouble
finding a copy.

JBWHOL.ZIP      Calculates predetermined English and German holidays and 
                adds them to the agenda.
                
FEIER10.ZIP     Calculates German holidays and adds them to the agenda.
                Probably configurable for other languages and holidays if 
                you make a few educated guesses about its data file format.

FTAG30.ZIP      Calculates and adds holidays related to easter and
                whitsun to the agenda. Includes OPL source.
                
EASTER_E.ZIP    English translation of FTAG30.ZIP
                
HOLI3A.ZIP      An agenda file with US holidays 1992-1997. 
                Some holidays are specified as repeating entries.


* Configuration

Holidays are defined by writing a holiday definition file. 
A holiday file is a text file with the file type .HOL. It contains
directives to the HOL program on what holidays to calculate and how to
write them to an agenda file.

The text in a holiday file consists of comments, keywords, punctuation
characters and quoted strings. 

A comment is any text after an exclamation mark or the keyword REM up to
the end of the current line. Keywords (e.g. STYLE) are not case
sensitive. A quoted string is any text within double quotes (e.g. "H").
A quoted string can not span lines. 

The file EXAMPLE.HOL explains the syntax with commented examples. Here
is a more formal looking definition:

<directive> : 
        <year-symbol-directive>
        <style-directive>
        <simple-holiday-directive>
        <compound-holiday-directive>

<compound-holiday-directive> : 
        { <local-directive-list> }

<local-directive-list> : 
        <local-directive>
        <local-directive-list local-directive>

<local-directive> : 
        <year-symbol-directive>
        <style-directive>
        <alias-directive>
        <simple-holiday-directive>

<year-symbol-directive> :
        YEAR_SYMBOL = " <year-symbol> " ;

<style-directive> :
        STYLE = <style-list> ;

<style-list> :
        <style>
        <style-list> , <style>

<style> :
        NORMAL
        BOLD
        ITALIC
        UNDERLINE

<alias-directive> :
        ALIAS = <alias> ;

<simple-holiday-directive>:
        " <holiday-name> " = <date-expression-list> ;

<date-expression-list> :
        <date-expression>
        <date-expression-list> <date-expression>

<date-expression> :
        <date-setter> 
        <date-modifier>
        <flow-control>

<date-setter> :
        <alias>
        FIX ( <value> , <value> )
        HFIX ( <value>, <value> )
        IFIX ( <value>, <value> )
        FLOAT ( <value> , <value> , <negvalue> <opt-value>(opt) )
        LAST ( <value> )
        EASTER

<opt-value> : 
        , <value>

<date-modifier> : 
        + <value>
        - <value>

<flow-control> :
        DONEIF ( <condition-list> )
        
<condition-list> : 
        <condition>
        <condition-list> OR <condition>
        
<condition> :
        WEEKDAY ( <value> )
        
<negvalue> :
        -(opt) <value>
        
<year-symbol>  = max one character.
<alias>        = a word with characters A-Z, max 33 characters.
<holiday-name> = a sequence of printable characters (except quote (")),
                 max 254 characters. If the text contains %IY or %HY
                 then those three characters will be replaced by 
                 the Islamic or Hebrew year for the calculated date.
<value>        = a positive number, digits 0-9


Functions:

FIX(month, day)
        Sets the date to day # DAY in month # MONTH. 
        Day and month numbers start at 1.

HFIX(month, day)
        Sets the date to day # DAY in Hebrew month # MONTH.
        Day and month numbers start at 1 (month 1 = Nisan).

IFIX(month, day)
        Sets the date to day # DAY in Islamic month # MONTH.
        Day and month numbers start at 1 (month 1 = Muharram).

FLOAT(month, weekday, n)
        Sets the date to the date of the Nth WEEKDAY in month # MONTH.
        Day and month numbers start at 1. N starts at 1. If N < 0 count 
        N WEEKDAYs from the end of the month. WEEKDAY numbers are from 
        0 (Sunday) to 6 (Saturday).

FLOAT(month, weekday, n, day)
        Sets the date to the date of the Nth WEEKDAY on or before/after 
        day # DAY in month # MONTH.
        Day and month numbers start at 1. N starts at 1. If N < 0 count 
        N WEEKDAYs before DAY MONTH, otherwise count N WEEKDAYs after 
        DAY MONTH. WEEKDAY numbers are from 0 (Sunday) to 6 (Saturday).
        
LAST(month)
        Sets the date to the date of the last day of month # MONTH.

EASTER
        Sets the date to the date of Easter Sunday (non-orthodox).
        
DONEIF(condition)
        If the condition is true then the rest of the current holiday
        directive (up to ';') will not be used.
        A condition is 'WEEKDAY(day)' or 'WEEKDAY(day) OR WEEKDAY(day)'
        etc.
        
WEEKDAY(weekday)
        Can only be used in DONEIF.
        Returns 'true' if the date is on the weekday specified as a
        parameter. WEEKDAY numbers are from 0 (Sunday) to 6 (Saturday).
        
        
* Limits

Line length in holiday file: 255 characters
Number of holiday definitions: 49
Number of aliases: 10
Number of characters in an alias: 33